PATHMac OS 8 Developer Documentation > Files > Navigation Services >

Programming With Navigation Services 1.1

DISCUSSION

After your application calls the NavGetFile function to display an Open dialog box and the user selects one or more files and clicks the Open button, NavGetFile closes the dialog box and returns references to the files to be opened in the NavReplyRecord structure. Your application should check the validRecord field of the NavReplyRecord structure; if this field is set to true , your application should open the files specified in the selection field of the NavReplyRecord structure.

SPECIAL CONSIDERATIONS

Always dispose of the NavReplyRecord structure after completing the file opening operation by calling the function NavDisposeReply . Failure to use the NavDisposeReply function causes memory used for the NavReplyRecord structure to remain allocated.

If you use the Show pop-up menu in an Open dialog box, your application must provide adequate kind strings to describe its native file types. For more information, see Providing File Format Options. For more information on kind strings, see Inside Macintosh: More Macintosh Toolbox .

SEE ALSO

For more information, see Opening Files.

For a sample code listing, see A Sample File-Saving Function.

NavChooseFile

Creates a simple dialog box that prompts the user to select a file.

OSErr NavChooseFile (AEDesc *defaultLocation,
                                         NavReplyRecord *reply,
                                         NavDialogOptions *dialogOptions,
                                         NavEventUPP eventProc,
                                         NavPreviewUPP previewProc,
                     NavObjectFilterUPP filterProc,
                     NavTypeListHandle typeList,
                                         void *callBackUD);

defaultLocation

A pointer to an Apple event descriptor structure ( AEDesc ). Before calling NavChooseFile , you can set up a structure of AEDesc type 'typeFSS' to specify a default location to be viewed. If you pass NULL in this parameter, Navigation Services displays the last location visited during a call to the NavChooseFile function. If the file system specification in the AEDesc structure does not describe a directory or volume, Navigation Services uses the desktop as the default location.

reply

A pointer to a structure of type NavReplyRecord . Upon return, Navigation Services uses this structure to provide data to your application about the results of your NavChooseFile call.

dialogOptions

A pointer to a structure of type NavDialogOptions . Before calling NavChooseFile , you can set up this structure to specify dialog box settings. If you pass NULL in this parameter, Navigation Services uses the defaults for all options. see Configuration Option Constants for a description of the default settings.

eventProc

A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the Choose a File dialog box is not movable or resizable. For more information, see Handling Events .

previewProc

A Universal Procedure Pointer (UPP) of type NavPreviewProcPtr that points to your application-defined preview function. Obtain this UPP by calling the function NewNavPreviewProc . A preview function allows your application to draw previews or to override Navigation Services previews. For more information, see Drawing Custom Previews.

filterProc

A Universal Procedure Pointer (UPP) of type NavFilterProcPtr that points to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterProc . An application-defined filter function determines if a volume, directory, or file should be displayed in the browser list or pop-up menus. For more information, see Filtering File Objects.

typeList

A handle to a structure of type NavTypeList . Before calling NavChooseFile , you can set up this structure to declare file types that your application can open. For more information, see Providing File Format Options.

callBackUD

A pointer to a value set by your application. When the NavChooseFile function calls your event-handling function, the callBackUD value is passed back to your application.

function result

see Result Codes for a list of result codes.

DISCUSSION

This function allows the user to choose a single file, such as a preferences file, for an action other than opening. The NavChooseFile function is similar to the NavGetFile function NavGetFile , but is limited to selecting a single file.

SPECIAL CONSIDERATIONS

The dialog box displayed by the NavChooseFile function does not display a Show menu. If you wish to control the files displayed by the browser list or the pop-up menus, you must specify a list of file types in the typeList parameter or specify a filter function in the filterProc parameter. If you specify a list of file types in the typeList parameter, the NavChooseFile function ignores the signature field of the NavTypeList structure. This means that all files of the types specified in the list of file types will be displayed, regardless of their application signature.

NavTranslateFile

Provides a means for files opened through Navigation Services to be read from different file formats.

OSErr NavTranslateFile (NavReplyRecord *translateInfo,
                                         NavTranslateOptions howToTranslate);

translateInfo

A pointer to a structure of type NavReplyRecord . Upon return, Navigation Services uses this structure to provide translation information about the selected files.

howToTranslate

A value of type NavTranslationOptions . Pass one of these constants to tell Navigation Services how to perform the translation: either in-place or to a copy. For a description of the constants, see Translation Option Constants.

function result

see Result Codes for a list of result codes.

DISCUSSION

Under automatic file translation, Navigation Services calls the NavTranslateFile function, if necessary, before returning from a file-opening function.

Your application can perform its own translation using the NavReplyRecord structure you specified in the translateInfo parameter. The NavReplyRecord structure contains a list of descriptors for the file or files to be opened. The NavReplyRecord structure also contains a corresponding list of translation specification records that can be passed to the Translation Manager. To determine if your application has to translate a file, your application can examine the NavReplyRecord structure to see if Navigation Services set the translationNeeded field to true . (The translationNeeded field of the NavReplyRecord structure is also set to true after returning from a NavGetFile call during which automatic translation was performed.) If you want to turn off automatic file translation, set the option kNavDontAutoTranslate in the dialogOptionFlags field of the structure of type NavDialogOptions that you pass in the dialogOptions parameter of the file-opening function.

If your application uses the NavTranslateFile function after opening a file without automatic translation, Navigation Services prompts the user to select a location in which to save the translated file if the source location cannot accept a new file (as occurs when the volume is locked or there is insufficient space). The same prompt may occur when automatic translation is enabled in an Open dialog box.

SEE ALSO

Translating Files on Open .

NavChooseVolume

Displays a dialog box that prompts the user to choose a volume.

OSErr NavChooseVolume(AEDesc *defaultSelection,
                                         NavReplyRecord *reply,
                                         NavDialogOptions *dialogOptions,
                                         NavEventUPP eventProc,
                                         NavFilterUPP filterProc,
                                         void *callBackUD);

defaultSelection

A pointer to an Apple event descriptor structure ( AEDesc ). Before calling NavChooseVolume , you can set up a structure of AEDesc type 'typeFSS' to specify a default location to be viewed. If you pass NULL in this parameter, Navigation Services displays the last location visited during a call to the NavChooseVolume function. If the file system specification in the AEDesc structure does not describe a directory or volume, Navigation Services uses the desktop as the default location.

reply

A pointer to a structure of type NavReplyRecord . Upon return, Navigation Services uses this structure to provide data to your application about the results of your NavChooseVolume call.

dialogOptions

A pointer to a structure of type NavDialogOptions . Before calling, set up this structure to specify dialog box settings. If you pass NULL in this parameter, Navigation Services uses the defaults for all options. see Configuration Option Constants for a description of the default settings.

eventProc

A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the Choose a Volume dialog box is not movable or resizable. For more information, see Handling Events .

filterProc

A Universal Procedure Pointer (UPP) of type NavFilterProcPtr that points to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterProc . An application-defined filter function determines if a volume, directory, or file should be displayed in the browser list or pop-up menus. For more information, see Filtering File Objects.

callBackUD

A pointer to a value set by your application. When the NavChooseVolume function calls your event-handling function, the callBackUD value is passed back to your application.

function result

see Result Codes for a list of result codes.

DISCUSSION

This function provides a way for your application to prompt the user to select a volume. This might be useful for a disk repair utility, for example.

NavChooseFolder

Displays a dialog box that prompts the user to choose a folder or volume.

OSErr NavChooseFolder(AEDesc *defaultLocation,
                                         NavReplyRecord *reply,
                                         NavDialogOptions *dialogOptions,
                                         NavEventUPP eventProc,
                                         NavObjectFilterUPP filterProc,
                                         void *callBackUD);

defaultLocation

A pointer to an Apple event descriptor structure ( AEDesc ). Before calling NavChooseFolder , you can set up a structure of AEDesc type 'typeFSS' to specify a default location to be viewed. If you pass NULL in this parameter, Navigation Services displays the last location visited during a call to the NavChooseFolder function. If the file system specification in the AEDesc structure does not describe a directory or volume, Navigation Services uses the desktop as the default location.

reply

A pointer to a structure of type NavReplyRecord . Upon return, Navigation Services uses this structure to provide data to your application about the results of your NavChooseFolder call.

dialogOptions

A pointer to a structure of type NavDialogOptions . Before calling NavChooseFolder , set up this structure to specify dialog box settings. If you pass NULL in this parameter, Navigation Services uses the defaults for all options. see Configuration Option Constants for a description of the default settings.

eventProc

A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the dialog box is not movable or resizable. For more information, see Handling Events .

filterProc

A Universal Procedure Pointer (UPP) of type NavFilterProcPtr that points to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterProc . An application-defined filter function determines if a volume, directory, or file should be displayed in the browser list or pop-up menus. For more information, see Filtering File Objects.

callBackUD

A pointer to a value set by your application. When the NavChooseFolder function calls your event-handling function, the callBackUD value is passed back to your application.

function result

see Result Codes for a list of result codes.

DISCUSSION

This function provides a way for your application to prompt the user to select a folder or volume. This might be useful if you need to install application files, for example.

NavChooseObject

Displays a dialog box that prompts the user to choose a file, folder, or volume.

OSErr NavChooseObject(AEDesc *defaultLocation,
                                         NavReplyRecord *reply,
                                         NavDialogOptions *dialogOptions,
                                         NavEventUPP eventProc,
                                         NavObjectFilterUPP filterProc,
                                         void *callBackUD);

defaultLocation

A pointer to an Apple event descriptor structure ( AEDesc ). Before calling NavChooseObject , you can set up a structure of AEDesc type 'typeFSS' to specify a default location to be viewed. If you pass NULL in this parameter, Navigation Services displays the last location visited during a call to the NavChooseObject function. If the file system specification in the AEDesc structure does not describe a directory or volume, Navigation Services uses the desktop as the default location.

reply

A pointer to a structure of type NavReplyRecord . Upon return, Navigation Services uses this structure to provide data to your application about the results of your NavChooseObject call.

dialogOptions

A pointer to a structure of type NavDialogOptions . Before calling NavChooseObject , set up this structure to specify dialog box settings. If you do not provide this structure, Navigation Services uses the defaults for all options. see Configuration Option Constants for a description of the default settings.

eventProc

A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the dialog box is not movable or resizable. For more information, see Handling Events .

filterProc

A Universal Procedure Pointer (UPP) of type NavFilterProcPtr that points to your application-defined filter function. Obtain this UPP by calling the function NewNavObjectFilterProc . An application-defined filter function determines if a volume, directory, or file should be displayed in the browser list or pop-up menus. For more information, see Filtering File Objects.

callBackUD

A pointer to a value set by your application. When the NavChooseObject function calls your event-handling function, the callBackUD value is passed back to your application.

function result

see Result Codes for a list of result codes.

DISCUSSION

This function is useful when you need to display a dialog box that prompts the user to choose a file object that might be a file, folder, or volume. If you want the user to choose a specific type of file object, you should use the function designed for that type of object; to select a file, for example, use the function NavChooseFile .

NavNewFolder

Displays a dialog box that prompts the user to create a new folder.

OSErr NavNewFolder  (AEDesc *defaultLocation,
                                         NavReplyRecord *reply,
                                         NavDialogOptions *dialogOptions,
                                         NavEventUPP eventProc,
                                         void *callBackUD);

defaultLocation

A pointer to an Apple event descriptor structure ( AEDesc ). Before calling NavNewFolder , you can set up a structure of AEDesc type 'typeFSS' to specify a default location to be viewed. If you pass NULL in this parameter, Navigation Services displays the last location visited during a call to the NavNewFolder function. If the file system specification in the AEDesc structure does not describe a directory or volume, Navigation Services uses the desktop as the default location.

reply

A pointer to a structure of type NavReplyRecord . Upon return, Navigation Services uses this structure to provide data to your application about the results of the NavNewFolder function call.

dialogOptions

A pointer to a structure of type NavDialogOptions . Before calling NavNewFolder , set up this structure to specify dialog box settings. If you pass NULL in this parameter, Navigation Services uses the defaults for all options. see Configuration Option Constants for a description of the default settings.

eventProc

A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the dialog box is not movable or resizable. For more information, see Handling Events .

callBackUD

A pointer to a value set by your application. When the NavNewFolder function calls your event-handling function, the callBackUD value is passed back to your application.

function result

see Result Codes for a list of result codes.

DISCUSSION

This function provides a way for your application to prompt the user to create a new folder. This might be useful for creating a project folder, for example.